<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<title>Kyoto Cabinet: Kyoto Cabinet: a straightforward implementation of DBM</title>

<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link href="doxygen.css" rel="stylesheet" type="text/css" />



</head>
<body>
<div id="top"><!-- do not remove this div! -->


<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  
  
  <td style="padding-left: 0.5em;">
   <div id="projectname">Kyoto Cabinet
   
   </div>
   
  </td>
  
  
  
 </tr>
 </tbody>
</table>
</div>

<!-- Generated by Doxygen 1.7.6.1 -->
  <div id="navrow1" class="tabs">
    <ul class="tablist">
      <li class="current"><a href="index.html"><span>Main&#160;Page</span></a></li>
      <li><a href="namespaces.html"><span>Namespaces</span></a></li>
      <li><a href="annotated.html"><span>Classes</span></a></li>
      <li><a href="files.html"><span>Files</span></a></li>
    </ul>
  </div>
</div>
<div class="header">
  <div class="headertitle">
<div class="title">Kyoto Cabinet: a straightforward implementation of DBM </div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><h2><a class="anchor" id="Introduction"></a>
Introduction</h2>
<p>Kyoto Cabinet is a library of routines for managing a database. The database is a simple data file containing records, each is a pair of a key and a value. Every key and value is serial bytes with variable length. Both binary data and character string can be used as a key and a value. Each key must be unique within a database. There is neither concept of data tables nor data types. Records are organized in hash table or B+ tree.</p>
<p>The following access methods are provided to the database: storing a record with a key and a value, deleting a record by a key, retrieving a record by a key. Moreover, traversal access to every key are provided. These access methods are similar to ones of the original DBM (and its followers: NDBM and GDBM) library defined in the UNIX standard. Kyoto Cabinet is an alternative for the DBM because of its higher performance.</p>
<p>Each operation of the hash database has the time complexity of "O(1)". Therefore, in theory, the performance is constant regardless of the scale of the database. In practice, the performance is determined by the speed of the main memory or the storage device. If the size of the database is less than the capacity of the main memory, the performance will seem on-memory speed, which is faster than std::map of STL. Of course, the database size can be greater than the capacity of the main memory and the upper limit is 8 exabytes. Even in that case, each operation needs only one or two seeking of the storage device.</p>
<p>Each operation of the B+ tree database has the time complexity of "O(log N)". Therefore, in theory, the performance is logarithmic to the scale of the database. Although the performance of random access of the B+ tree database is slower than that of the hash database, the B+ tree database supports sequential access in order of the keys, which realizes forward matching search for strings and range search for integers. The performance of sequential access is much faster than that of random access.</p>
<p>As the API is based on object-oriented design, the hash database and the the B+ tree database have same methods which inherited from the upper abstract class. Beside them, seven kinds of databases are provided under the same base class. The prototype hash database is powered by the standard container of std::unordered_map. The prototype tree database is powered by the standard container of std::map. The stash database is powered by the original implementation of naive hash map saving memory. The cache hash database is powered by the original implementation of doubly-linked hash map with LRU deletion algorithm. The cache tree database is powered by the cache hash database and provides B+ tree mechanism. The directory hash database is powered by the directory mechanism of the file system and stores records as respective files in a directory. The directory tree database is powered by the directory hash database and provides B+ tree mechanism. All databases have practical utility methods related to transaction and cursor. Programs for command line interface are also included in the package.</p>
<p>All databases have practical utility methods related to transaction and cursor. Programs for command line interface are also included in the package.</p>
<p>The following classes are most important. If you are new to Kyoto Cabinet, learn the polymorphic database first.</p>
<ul>
<li><a class="el" href="classkyotocabinet_1_1BasicDB.html" title="Basic implementation of database.">kyotocabinet::BasicDB</a> -- common interface of concrete databases </li>
<li><a class="el" href="namespacekyotocabinet.html#a68826fcd903705a08001af0180d713e6" title="An alias of the prototype hash database.">kyotocabinet::ProtoHashDB</a> -- on-memory hash database based on std::unordered_map </li>
<li><a class="el" href="namespacekyotocabinet.html#a7d8bb1fb74782bff49ec28d486c98801" title="An alias of the prototype tree database.">kyotocabinet::ProtoTreeDB</a> -- on-memory hash database based on std::map </li>
<li><a class="el" href="classkyotocabinet_1_1StashDB.html" title="Economical on-memory hash database.">kyotocabinet::StashDB</a> -- economical on-memory hash database for cache. </li>
<li><a class="el" href="classkyotocabinet_1_1CacheDB.html" title="On-memory hash database with LRU deletion.">kyotocabinet::CacheDB</a> -- on-memory hash database for cache with LRU deletion </li>
<li><a class="el" href="namespacekyotocabinet.html#ab08bf5f25c36e8e6b06e7531b047acc7" title="An alias of the cache tree database.">kyotocabinet::GrassDB</a> -- on-memory tree database for cache in order </li>
<li><a class="el" href="classkyotocabinet_1_1HashDB.html" title="File hash database.">kyotocabinet::HashDB</a> -- file hash database, which implements hash table on a file </li>
<li><a class="el" href="namespacekyotocabinet.html#a58209fa250ad75178ca0379f1034ad5e" title="An alias of the file tree database.">kyotocabinet::TreeDB</a> -- file tree database, which implements B+ tree on a file </li>
<li><a class="el" href="classkyotocabinet_1_1DirDB.html" title="Directory hash database.">kyotocabinet::DirDB</a> -- directory hash database, which handles respective files in a directory </li>
<li><a class="el" href="namespacekyotocabinet.html#aadca6acd45bcad111229c9f92be7a66b" title="An alias of the directory tree database.">kyotocabinet::ForestDB</a> -- directory tree database, which implements B+ tree on a directory </li>
<li><a class="el" href="classkyotocabinet_1_1TextDB.html" title="Plain text database.">kyotocabinet::TextDB</a> -- plain text database, which treats a text file as a database </li>
<li><a class="el" href="classkyotocabinet_1_1PolyDB.html" title="Polymorphic database.">kyotocabinet::PolyDB</a> -- polymorphic database, dynamic binding of the above databases</li>
</ul>
<ul>
<li><a class="el" href="classkyotocabinet_1_1MapReduce.html" title="MapReduce framework.">kyotocabinet::MapReduce</a> -- MapReduce framework to process records in each database </li>
<li><a class="el" href="classkyotocabinet_1_1IndexDB.html" title="Index database.">kyotocabinet::IndexDB</a> -- wrapper for efficient appending operations to each database</li>
</ul>
<ul>
<li><a class="el" href="kclangc_8h.html" title="C language binding.">kclangc.h</a> -- C language binding of the polymorphic database</li>
</ul>
<p>See the project homepage ( <a href="http://fallabs.com/kyotocabinet/">http://fallabs.com/kyotocabinet/</a> ) for details.</p>
<h2><a class="anchor" id="Example"></a>
Example</h2>
<p>The following code is an example to use a polymorphic database.</p>
<div class="fragment"><pre class="fragment"><span class="preprocessor">#include &lt;<a class="code" href="kcpolydb_8h.html" title="polymorphic database">kcpolydb.h</a>&gt;</span>

<span class="keyword">using namespace </span>std;
<span class="keyword">using namespace </span>kyotocabinet;

<span class="comment">// main routine</span>
<span class="keywordtype">int</span> main(<span class="keywordtype">int</span> argc, <span class="keywordtype">char</span>** argv) {

  <span class="comment">// create the database object</span>
  <a class="code" href="classkyotocabinet_1_1PolyDB.html" title="Polymorphic database.">PolyDB</a> db;

  <span class="comment">// open the database</span>
  <span class="keywordflow">if</span> (!db.<a class="code" href="classkyotocabinet_1_1PolyDB.html#a09384a72e6a72a0be98c80a1856f34aa" title="Open a database file.">open</a>(<span class="stringliteral">&quot;casket.kch&quot;</span>, PolyDB::OWRITER | PolyDB::OCREATE)) {
    cerr &lt;&lt; <span class="stringliteral">&quot;open error: &quot;</span> &lt;&lt; db.<a class="code" href="classkyotocabinet_1_1PolyDB.html#a7d247b16ee5250e1ed7b2768f6e030c3" title="Get the last happened error.">error</a>().<a class="code" href="classkyotocabinet_1_1BasicDB_1_1Error.html#abdb12a2ca2df5add3409e9bba230baa4" title="Get the readable string of the code.">name</a>() &lt;&lt; endl;
  }

  <span class="comment">// store records</span>
  <span class="keywordflow">if</span> (!db.<a class="code" href="classkyotocabinet_1_1BasicDB.html#ace1d7f4a0d37c2d4e61b102bc0d0f725" title="Set the value of a record.">set</a>(<span class="stringliteral">&quot;foo&quot;</span>, <span class="stringliteral">&quot;hop&quot;</span>) ||
      !db.<a class="code" href="classkyotocabinet_1_1BasicDB.html#ace1d7f4a0d37c2d4e61b102bc0d0f725" title="Set the value of a record.">set</a>(<span class="stringliteral">&quot;bar&quot;</span>, <span class="stringliteral">&quot;step&quot;</span>) ||
      !db.<a class="code" href="classkyotocabinet_1_1BasicDB.html#ace1d7f4a0d37c2d4e61b102bc0d0f725" title="Set the value of a record.">set</a>(<span class="stringliteral">&quot;baz&quot;</span>, <span class="stringliteral">&quot;jump&quot;</span>)) {
    cerr &lt;&lt; <span class="stringliteral">&quot;set error: &quot;</span> &lt;&lt; db.<a class="code" href="classkyotocabinet_1_1PolyDB.html#a7d247b16ee5250e1ed7b2768f6e030c3" title="Get the last happened error.">error</a>().<a class="code" href="classkyotocabinet_1_1BasicDB_1_1Error.html#abdb12a2ca2df5add3409e9bba230baa4" title="Get the readable string of the code.">name</a>() &lt;&lt; endl;
  }

  <span class="comment">// retrieve a record</span>
  <span class="keywordtype">string</span> value;
  <span class="keywordflow">if</span> (db.<a class="code" href="classkyotocabinet_1_1BasicDB.html#a04721eb5a61876244bbc5c08e0a34c61" title="Retrieve the value of a record.">get</a>(<span class="stringliteral">&quot;foo&quot;</span>, &amp;value)) {
    cout &lt;&lt; value &lt;&lt; endl;
  } <span class="keywordflow">else</span> {
    cerr &lt;&lt; <span class="stringliteral">&quot;get error: &quot;</span> &lt;&lt; db.<a class="code" href="classkyotocabinet_1_1PolyDB.html#a7d247b16ee5250e1ed7b2768f6e030c3" title="Get the last happened error.">error</a>().<a class="code" href="classkyotocabinet_1_1BasicDB_1_1Error.html#abdb12a2ca2df5add3409e9bba230baa4" title="Get the readable string of the code.">name</a>() &lt;&lt; endl;
  }

  <span class="comment">// traverse records</span>
  <a class="code" href="classkyotocabinet_1_1DB_1_1Cursor.html" title="Interface of cursor to indicate a record.">DB::Cursor</a>* cur = db.<a class="code" href="classkyotocabinet_1_1PolyDB.html#a54f983af2afab8f667d1e28595b224c2" title="Create a cursor object.">cursor</a>();
  cur-&gt;<a class="code" href="classkyotocabinet_1_1DB_1_1Cursor.html#a9b7e9982b948d66a4d2a0295229ac4c1" title="Jump the cursor to the first record for forward scan.">jump</a>();
  <span class="keywordtype">string</span> ckey, cvalue;
  <span class="keywordflow">while</span> (cur-&gt;<a class="code" href="classkyotocabinet_1_1DB_1_1Cursor.html#a556bb019a558a6279e4778361e889289" title="Get a pair of the key and the value of the current record.">get</a>(&amp;ckey, &amp;cvalue, <span class="keyword">true</span>)) {
    cout &lt;&lt; ckey &lt;&lt; <span class="stringliteral">&quot;:&quot;</span> &lt;&lt; cvalue &lt;&lt; endl;
  }
  <span class="keyword">delete</span> cur;

  <span class="comment">// close the database</span>
  <span class="keywordflow">if</span> (!db.<a class="code" href="classkyotocabinet_1_1PolyDB.html#acf5dd748aed15bb2866e8f12c6e2b3f8" title="Close the database file.">close</a>()) {
    cerr &lt;&lt; <span class="stringliteral">&quot;close error: &quot;</span> &lt;&lt; db.<a class="code" href="classkyotocabinet_1_1PolyDB.html#a7d247b16ee5250e1ed7b2768f6e030c3" title="Get the last happened error.">error</a>().<a class="code" href="classkyotocabinet_1_1BasicDB_1_1Error.html#abdb12a2ca2df5add3409e9bba230baa4" title="Get the readable string of the code.">name</a>() &lt;&lt; endl;
  }

  <span class="keywordflow">return</span> 0;
}
</pre></div><p>The following code is a more complex example, which uses the Visitor pattern.</p>
<div class="fragment"><pre class="fragment"><span class="preprocessor">#include &lt;<a class="code" href="kcpolydb_8h.html" title="polymorphic database">kcpolydb.h</a>&gt;</span>

<span class="keyword">using namespace </span>std;
<span class="keyword">using namespace </span>kyotocabinet;

<span class="comment">// main routine</span>
<span class="keywordtype">int</span> main(<span class="keywordtype">int</span> argc, <span class="keywordtype">char</span>** argv) {

  <span class="comment">// create the database object</span>
  <a class="code" href="classkyotocabinet_1_1PolyDB.html" title="Polymorphic database.">PolyDB</a> db;

  <span class="comment">// open the database</span>
  <span class="keywordflow">if</span> (!db.<a class="code" href="classkyotocabinet_1_1PolyDB.html#a09384a72e6a72a0be98c80a1856f34aa" title="Open a database file.">open</a>(<span class="stringliteral">&quot;casket.kch&quot;</span>, PolyDB::OREADER)) {
    cerr &lt;&lt; <span class="stringliteral">&quot;open error: &quot;</span> &lt;&lt; db.<a class="code" href="classkyotocabinet_1_1PolyDB.html#a7d247b16ee5250e1ed7b2768f6e030c3" title="Get the last happened error.">error</a>().<a class="code" href="classkyotocabinet_1_1BasicDB_1_1Error.html#abdb12a2ca2df5add3409e9bba230baa4" title="Get the readable string of the code.">name</a>() &lt;&lt; endl;
  }

  <span class="comment">// define the visitor</span>
  <span class="keyword">class </span>VisitorImpl : <span class="keyword">public</span> <a class="code" href="classkyotocabinet_1_1DB.html" title="Interface of database abstraction.">DB</a>::Visitor {
    <span class="comment">// call back function for an existing record</span>
    <span class="keyword">const</span> <span class="keywordtype">char</span>* visit_full(<span class="keyword">const</span> <span class="keywordtype">char</span>* kbuf, <span class="keywordtype">size_t</span> ksiz,
                           <span class="keyword">const</span> <span class="keywordtype">char</span>* vbuf, <span class="keywordtype">size_t</span> vsiz, <span class="keywordtype">size_t</span> *sp) {
      cout &lt;&lt; string(kbuf, ksiz) &lt;&lt; <span class="stringliteral">&quot;:&quot;</span> &lt;&lt; string(vbuf, vsiz) &lt;&lt; endl;
      <span class="keywordflow">return</span> NOP;
    }
    <span class="comment">// call back function for an empty record space</span>
    <span class="keyword">const</span> <span class="keywordtype">char</span>* visit_empty(<span class="keyword">const</span> <span class="keywordtype">char</span>* kbuf, <span class="keywordtype">size_t</span> ksiz, <span class="keywordtype">size_t</span> *sp) {
      cerr &lt;&lt; string(kbuf, ksiz) &lt;&lt; <span class="stringliteral">&quot; is missing&quot;</span> &lt;&lt; endl;
      <span class="keywordflow">return</span> NOP;
    }
  } visitor;

  <span class="comment">// retrieve a record with visitor</span>
  <span class="keywordflow">if</span> (!db.<a class="code" href="classkyotocabinet_1_1PolyDB.html#abfadd89cc0469d9abfc180b1f7f06f8d" title="Accept a visitor to a record.">accept</a>(<span class="stringliteral">&quot;foo&quot;</span>, 3, &amp;visitor, <span class="keyword">false</span>) ||
      !db.<a class="code" href="classkyotocabinet_1_1PolyDB.html#abfadd89cc0469d9abfc180b1f7f06f8d" title="Accept a visitor to a record.">accept</a>(<span class="stringliteral">&quot;dummy&quot;</span>, 5, &amp;visitor, <span class="keyword">false</span>)) {
    cerr &lt;&lt; <span class="stringliteral">&quot;accept error: &quot;</span> &lt;&lt; db.<a class="code" href="classkyotocabinet_1_1PolyDB.html#a7d247b16ee5250e1ed7b2768f6e030c3" title="Get the last happened error.">error</a>().<a class="code" href="classkyotocabinet_1_1BasicDB_1_1Error.html#abdb12a2ca2df5add3409e9bba230baa4" title="Get the readable string of the code.">name</a>() &lt;&lt; endl;
  }

  <span class="comment">// traverse records with visitor</span>
  <span class="keywordflow">if</span> (!db.<a class="code" href="classkyotocabinet_1_1PolyDB.html#a27be5998494e81a5fa4be24e6047f4de" title="Iterate to accept a visitor for each record.">iterate</a>(&amp;visitor, <span class="keyword">false</span>)) {
    cerr &lt;&lt; <span class="stringliteral">&quot;iterate error: &quot;</span> &lt;&lt; db.<a class="code" href="classkyotocabinet_1_1PolyDB.html#a7d247b16ee5250e1ed7b2768f6e030c3" title="Get the last happened error.">error</a>().<a class="code" href="classkyotocabinet_1_1BasicDB_1_1Error.html#abdb12a2ca2df5add3409e9bba230baa4" title="Get the readable string of the code.">name</a>() &lt;&lt; endl;
  }

  <span class="comment">// close the database</span>
  <span class="keywordflow">if</span> (!db.<a class="code" href="classkyotocabinet_1_1PolyDB.html#acf5dd748aed15bb2866e8f12c6e2b3f8" title="Close the database file.">close</a>()) {
    cerr &lt;&lt; <span class="stringliteral">&quot;close error: &quot;</span> &lt;&lt; db.<a class="code" href="classkyotocabinet_1_1PolyDB.html#a7d247b16ee5250e1ed7b2768f6e030c3" title="Get the last happened error.">error</a>().<a class="code" href="classkyotocabinet_1_1BasicDB_1_1Error.html#abdb12a2ca2df5add3409e9bba230baa4" title="Get the readable string of the code.">name</a>() &lt;&lt; endl;
  }

  <span class="keywordflow">return</span> 0;
}
</pre></div><p>The following code is an example of word counting with the MapReduce framework.</p>
<div class="fragment"><pre class="fragment"><span class="preprocessor">#include &lt;<a class="code" href="kcpolydb_8h.html" title="polymorphic database">kcpolydb.h</a>&gt;</span>
<span class="preprocessor">#include &lt;<a class="code" href="kcdbext_8h.html" title="database extension">kcdbext.h</a>&gt;</span>

<span class="keyword">using namespace </span>std;
<span class="keyword">using namespace </span>kyotocabinet;

<span class="comment">// main routine</span>
<span class="keywordtype">int</span> main(<span class="keywordtype">int</span> argc, <span class="keywordtype">char</span>** argv) {

  <span class="comment">// create the database object</span>
  <a class="code" href="classkyotocabinet_1_1PolyDB.html" title="Polymorphic database.">PolyDB</a> db;

  <span class="comment">// open the database</span>
  <span class="keywordflow">if</span> (!db.<a class="code" href="classkyotocabinet_1_1PolyDB.html#a09384a72e6a72a0be98c80a1856f34aa" title="Open a database file.">open</a>()) {
    cerr &lt;&lt; <span class="stringliteral">&quot;open error: &quot;</span> &lt;&lt; db.<a class="code" href="classkyotocabinet_1_1PolyDB.html#a7d247b16ee5250e1ed7b2768f6e030c3" title="Get the last happened error.">error</a>().<a class="code" href="classkyotocabinet_1_1BasicDB_1_1Error.html#abdb12a2ca2df5add3409e9bba230baa4" title="Get the readable string of the code.">name</a>() &lt;&lt; endl;
  }

  <span class="comment">// store records</span>
  db.<a class="code" href="classkyotocabinet_1_1BasicDB.html#ace1d7f4a0d37c2d4e61b102bc0d0f725" title="Set the value of a record.">set</a>(<span class="stringliteral">&quot;1&quot;</span>, <span class="stringliteral">&quot;this is a pen&quot;</span>);
  db.<a class="code" href="classkyotocabinet_1_1BasicDB.html#ace1d7f4a0d37c2d4e61b102bc0d0f725" title="Set the value of a record.">set</a>(<span class="stringliteral">&quot;2&quot;</span>, <span class="stringliteral">&quot;what a beautiful pen this is&quot;</span>);
  db.<a class="code" href="classkyotocabinet_1_1BasicDB.html#ace1d7f4a0d37c2d4e61b102bc0d0f725" title="Set the value of a record.">set</a>(<span class="stringliteral">&quot;3&quot;</span>, <span class="stringliteral">&quot;she is beautiful&quot;</span>);

  <span class="comment">// define the mapper and the reducer</span>
  <span class="keyword">class </span>MapReduceImpl : <span class="keyword">public</span> <a class="code" href="classkyotocabinet_1_1MapReduce.html" title="MapReduce framework.">MapReduce</a> {
    <span class="comment">// call back function of the mapper</span>
    <span class="keywordtype">bool</span> map(<span class="keyword">const</span> <span class="keywordtype">char</span>* kbuf, <span class="keywordtype">size_t</span> ksiz, <span class="keyword">const</span> <span class="keywordtype">char</span>* vbuf, <span class="keywordtype">size_t</span> vsiz) {
      vector&lt;string&gt; words;
      <a class="code" href="namespacekyotocabinet.html#a295fcdb0ba9274e2d986a66e1eb189b8" title="Split a string with a delimiter.">strsplit</a>(<span class="keywordtype">string</span>(vbuf, vsiz), <span class="charliteral">&#39; &#39;</span>, &amp;words);
      <span class="keywordflow">for</span> (vector&lt;string&gt;::iterator it = words.begin();
           it != words.end(); it++) {
        emit(it-&gt;data(), it-&gt;size(), <span class="stringliteral">&quot;&quot;</span>, 0);
      }
      <span class="keywordflow">return</span> <span class="keyword">true</span>;
    }
    <span class="comment">// call back function of the reducer</span>
    <span class="keywordtype">bool</span> reduce(<span class="keyword">const</span> <span class="keywordtype">char</span>* kbuf, <span class="keywordtype">size_t</span> ksiz, ValueIterator* iter) {
      <span class="keywordtype">size_t</span> count = 0;
      <span class="keyword">const</span> <span class="keywordtype">char</span>* vbuf;
      <span class="keywordtype">size_t</span> vsiz;
      <span class="keywordflow">while</span> ((vbuf = iter-&gt;next(&amp;vsiz)) != NULL) {
        count++;
      }
      cout &lt;&lt; string(kbuf, ksiz) &lt;&lt; <span class="stringliteral">&quot;: &quot;</span> &lt;&lt; count &lt;&lt; endl;
      <span class="keywordflow">return</span> <span class="keyword">true</span>;
    }
  } mr;

  <span class="comment">// execute the MapReduce process</span>
  <span class="keywordflow">if</span> (!mr.execute(&amp;db)) {
    cerr &lt;&lt; <span class="stringliteral">&quot;MapReduce error: &quot;</span> &lt;&lt; db.<a class="code" href="classkyotocabinet_1_1PolyDB.html#a7d247b16ee5250e1ed7b2768f6e030c3" title="Get the last happened error.">error</a>().<a class="code" href="classkyotocabinet_1_1BasicDB_1_1Error.html#abdb12a2ca2df5add3409e9bba230baa4" title="Get the readable string of the code.">name</a>() &lt;&lt; endl;
  }

  <span class="comment">// close the database</span>
  <span class="keywordflow">if</span> (!db.<a class="code" href="classkyotocabinet_1_1PolyDB.html#acf5dd748aed15bb2866e8f12c6e2b3f8" title="Close the database file.">close</a>()) {
    cerr &lt;&lt; <span class="stringliteral">&quot;close error: &quot;</span> &lt;&lt; db.<a class="code" href="classkyotocabinet_1_1PolyDB.html#a7d247b16ee5250e1ed7b2768f6e030c3" title="Get the last happened error.">error</a>().<a class="code" href="classkyotocabinet_1_1BasicDB_1_1Error.html#abdb12a2ca2df5add3409e9bba230baa4" title="Get the readable string of the code.">name</a>() &lt;&lt; endl;
  }

  <span class="keywordflow">return</span> 0;
}
</pre></div><p>The C language binding is also provided as a wrapper of the polymorphic database API. The following code is an example.</p>
<div class="fragment"><pre class="fragment"><span class="preprocessor">#include &lt;<a class="code" href="kclangc_8h.html" title="C language binding.">kclangc.h</a>&gt;</span>

<span class="comment">/* call back function for an existing record */</span>
<span class="keyword">const</span> <span class="keywordtype">char</span>* visitfull(<span class="keyword">const</span> <span class="keywordtype">char</span>* kbuf, <span class="keywordtype">size_t</span> ksiz,
                      <span class="keyword">const</span> <span class="keywordtype">char</span>* vbuf, <span class="keywordtype">size_t</span> vsiz, <span class="keywordtype">size_t</span> *sp, <span class="keywordtype">void</span>* opq) {
  fwrite(kbuf, 1, ksiz, stdout);
  printf(<span class="stringliteral">&quot;:&quot;</span>);
  fwrite(vbuf, 1, vsiz, stdout);
  printf(<span class="stringliteral">&quot;\n&quot;</span>);
  <span class="keywordflow">return</span> <a class="code" href="kclangc_8h.html#a64c59ac34c88a862d2066d9097b09504" title="Special pointer for no operation by the visiting function.">KCVISNOP</a>;
}

<span class="comment">/* call back function for an empty record space */</span>
<span class="keyword">const</span> <span class="keywordtype">char</span>* visitempty(<span class="keyword">const</span> <span class="keywordtype">char</span>* kbuf, <span class="keywordtype">size_t</span> ksiz, <span class="keywordtype">size_t</span> *sp, <span class="keywordtype">void</span>* opq) {
  fwrite(kbuf, 1, ksiz, stdout);
  printf(<span class="stringliteral">&quot; is missing\n&quot;</span>);
  <span class="keywordflow">return</span> <a class="code" href="kclangc_8h.html#a64c59ac34c88a862d2066d9097b09504" title="Special pointer for no operation by the visiting function.">KCVISNOP</a>;
}

<span class="comment">/* main routine */</span>
<span class="keywordtype">int</span> main(<span class="keywordtype">int</span> argc, <span class="keywordtype">char</span>** argv) {
  <a class="code" href="structKCDB.html" title="C wrapper of polymorphic database.">KCDB</a>* db;
  <a class="code" href="structKCCUR.html" title="C wrapper of polymorphic cursor.">KCCUR</a>* cur;
  <span class="keywordtype">char</span> *kbuf, *vbuf;
  <span class="keywordtype">size_t</span> ksiz, vsiz;
  <span class="keyword">const</span> <span class="keywordtype">char</span> *cvbuf;

  <span class="comment">/* create the database object */</span>
  db = <a class="code" href="kclangc_8h.html#a485c6993061575b14c4615988e694a15" title="Create a polymorphic database object.">kcdbnew</a>();

  <span class="comment">/* open the database */</span>
  <span class="keywordflow">if</span> (!<a class="code" href="kclangc_8h.html#a464237fa818e4b70b15526a898b5c5f5" title="Open a database file.">kcdbopen</a>(db, <span class="stringliteral">&quot;casket.kch&quot;</span>, <a class="code" href="kclangc_8h.html#adf764cbdea00d65edcd07bb9953ad2b7a352bdce1311ada70fcaf2f22194cbbdf" title="open as a writer">KCOWRITER</a> | <a class="code" href="kclangc_8h.html#adf764cbdea00d65edcd07bb9953ad2b7a8aae26396f1c8062f63ff6319430116f" title="writer creating">KCOCREATE</a>)) {
    fprintf(stderr, <span class="stringliteral">&quot;open error: %s\n&quot;</span>, <a class="code" href="kclangc_8h.html#a7c345d19eb7072e55e54091467d269d7" title="Get the readable string of an error code.">kcecodename</a>(<a class="code" href="kclangc_8h.html#a686a89045f646d5a7bbb87f264cd7e3a" title="Get the code of the last happened error.">kcdbecode</a>(db)));
  }

  <span class="comment">/* store records */</span>
  <span class="keywordflow">if</span> (!<a class="code" href="kclangc_8h.html#acc94df95a0d8863c450a649bdc546eaf" title="Set the value of a record.">kcdbset</a>(db, <span class="stringliteral">&quot;foo&quot;</span>, 3, <span class="stringliteral">&quot;hop&quot;</span>, 3) ||
      !<a class="code" href="kclangc_8h.html#acc94df95a0d8863c450a649bdc546eaf" title="Set the value of a record.">kcdbset</a>(db, <span class="stringliteral">&quot;bar&quot;</span>, 3, <span class="stringliteral">&quot;step&quot;</span>, 4) ||
      !<a class="code" href="kclangc_8h.html#acc94df95a0d8863c450a649bdc546eaf" title="Set the value of a record.">kcdbset</a>(db, <span class="stringliteral">&quot;baz&quot;</span>, 3, <span class="stringliteral">&quot;jump&quot;</span>, 4)) {
    fprintf(stderr, <span class="stringliteral">&quot;set error: %s\n&quot;</span>, <a class="code" href="kclangc_8h.html#a7c345d19eb7072e55e54091467d269d7" title="Get the readable string of an error code.">kcecodename</a>(<a class="code" href="kclangc_8h.html#a686a89045f646d5a7bbb87f264cd7e3a" title="Get the code of the last happened error.">kcdbecode</a>(db)));
  }

  <span class="comment">/* retrieve a record */</span>
  vbuf = <a class="code" href="kclangc_8h.html#ab552d20a2af1375b24aba34f412302d0" title="Retrieve the value of a record.">kcdbget</a>(db, <span class="stringliteral">&quot;foo&quot;</span>, 3, &amp;vsiz);
  <span class="keywordflow">if</span> (vbuf) {
    printf(<span class="stringliteral">&quot;%s\n&quot;</span>, vbuf);
    <a class="code" href="kclangc_8h.html#aba875623bd102d078eb328a1eb7bc0f6" title="Release a region allocated in the library.">kcfree</a>(vbuf);
  } <span class="keywordflow">else</span> {
    fprintf(stderr, <span class="stringliteral">&quot;get error: %s\n&quot;</span>, <a class="code" href="kclangc_8h.html#a7c345d19eb7072e55e54091467d269d7" title="Get the readable string of an error code.">kcecodename</a>(<a class="code" href="kclangc_8h.html#a686a89045f646d5a7bbb87f264cd7e3a" title="Get the code of the last happened error.">kcdbecode</a>(db)));
  }

  <span class="comment">/* traverse records */</span>
  cur = <a class="code" href="kclangc_8h.html#adccaf4771f7804511791af33a316e0ba" title="Create a polymorphic cursor object.">kcdbcursor</a>(db);
  <a class="code" href="kclangc_8h.html#a086c2e825133e414430ebd9fa010c9e0" title="Jump the cursor to the first record for forward scan.">kccurjump</a>(cur);
  <span class="keywordflow">while</span> ((kbuf = <a class="code" href="kclangc_8h.html#a543b0095fb011f3ae42424460190d25a" title="Get a pair of the key and the value of the current record.">kccurget</a>(cur, &amp;ksiz, &amp;cvbuf, &amp;vsiz, 1)) != NULL) {
    printf(<span class="stringliteral">&quot;%s:%s\n&quot;</span>, kbuf, cvbuf);
    <a class="code" href="kclangc_8h.html#aba875623bd102d078eb328a1eb7bc0f6" title="Release a region allocated in the library.">kcfree</a>(kbuf);
  }
  <a class="code" href="kclangc_8h.html#a88d85075827598fa94c6fd4c3430389f" title="Destroy a cursor object.">kccurdel</a>(cur);

  <span class="comment">/* retrieve a record with visitor */</span>
  <span class="keywordflow">if</span> (!<a class="code" href="kclangc_8h.html#a6bca0b4da37a96a6673e834567a7886a" title="Accept a visitor to a record.">kcdbaccept</a>(db, <span class="stringliteral">&quot;foo&quot;</span>, 3, visitfull, visitempty, NULL, 0) ||
      !<a class="code" href="kclangc_8h.html#a6bca0b4da37a96a6673e834567a7886a" title="Accept a visitor to a record.">kcdbaccept</a>(db, <span class="stringliteral">&quot;dummy&quot;</span>, 5, visitfull, visitempty, NULL, 0)) {
    fprintf(stderr, <span class="stringliteral">&quot;accept error: %s\n&quot;</span>, <a class="code" href="kclangc_8h.html#a7c345d19eb7072e55e54091467d269d7" title="Get the readable string of an error code.">kcecodename</a>(<a class="code" href="kclangc_8h.html#a686a89045f646d5a7bbb87f264cd7e3a" title="Get the code of the last happened error.">kcdbecode</a>(db)));
  }

  <span class="comment">/* traverse records with visitor */</span>
  <span class="keywordflow">if</span> (!<a class="code" href="kclangc_8h.html#a01828d3ba1b4e624683faea5311cfac0" title="Iterate to accept a visitor for each record.">kcdbiterate</a>(db, visitfull, NULL, 0)) {
    fprintf(stderr, <span class="stringliteral">&quot;iterate error: %s\n&quot;</span>, <a class="code" href="kclangc_8h.html#a7c345d19eb7072e55e54091467d269d7" title="Get the readable string of an error code.">kcecodename</a>(<a class="code" href="kclangc_8h.html#a686a89045f646d5a7bbb87f264cd7e3a" title="Get the code of the last happened error.">kcdbecode</a>(db)));
  }

  <span class="comment">/* close the database */</span>
  <span class="keywordflow">if</span> (!<a class="code" href="kclangc_8h.html#adbbfc05c79211f4f70f179579f4f3f00" title="Close the database file.">kcdbclose</a>(db)) {
    fprintf(stderr, <span class="stringliteral">&quot;close error: %s\n&quot;</span>, <a class="code" href="kclangc_8h.html#a7c345d19eb7072e55e54091467d269d7" title="Get the readable string of an error code.">kcecodename</a>(<a class="code" href="kclangc_8h.html#a686a89045f646d5a7bbb87f264cd7e3a" title="Get the code of the last happened error.">kcdbecode</a>(db)));
  }

  <span class="comment">/* delete the database object */</span>
  <a class="code" href="kclangc_8h.html#a6bbf9098efff747475f6e9098a8a6844" title="Destroy a database object.">kcdbdel</a>(db);

  <span class="keywordflow">return</span> 0;
}
</pre></div> </div></div><!-- contents -->


<hr class="footer"/><address class="footer"><small>
Generated on Fri May 25 2012 01:21:36 for Kyoto Cabinet by &#160;<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.7.6.1
</small></address>

</body>
</html>
